home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat4 / hwgraph.z / hwgraph
Encoding:
Text File  |  2001-04-17  |  11.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. hhhhwwwwggggrrrraaaapppphhhh((((4444))))                                                          hhhhwwwwggggrrrraaaapppphhhh((((4444))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      hwgraph, hwgfs, hw - hardware graph and hardware graph file system
  10.  
  11. IIIInnnntttteeeerrrrnnnnaaaallll HHHHaaaarrrrddddwwwwaaaarrrreeee GGGGrrrraaaapppphhhh
  12.      Internally, Irix system software maintains a directed graph called the
  13.      "hardware graph". The hwgraph represents the collection of all
  14.      significant hardware connected to a system.  It represents each piece of
  15.      hardware -- modules, CPUs, memories, disk controllers, disk drives, disk
  16.      partitions, serial ports, ethernet ports, some system integrated
  17.      circuits, etc. -- as a distinct vertex in the graph.   There are some
  18.      additional vertices that represent collections of hardware (e.g. "the
  19.      disks") or more abstract architectural concepts (e.g. "a node").  The
  20.      contents of the hardware graph are obviously system-dependent; but there
  21.      are many common elements that cross system types.
  22.  
  23.      Labeled edges are used to connect graph vertexes in a way that shows some
  24.      relationship between the underlying hardware.  For instance, an edge
  25.      labeled "3" originates at a vertex that represents the collection of all
  26.      partitions on a drive.  It points to a vertex that represents the third
  27.      partition on that drive.  Another example: An edge labeled "memory"
  28.      hanging off a vertex that represents a system node points to a vertex
  29.      that represents the memory on that node.
  30.  
  31.      The internal hwgraph also supports arbitrarily-labeled information
  32.      associated with each vertex.  This allows device drivers to associate
  33.      useful data structures and other information with a particular device.
  34.  
  35.      The hardware graph is maintained by system software with the cooperation
  36.      of device drivers using new device driver interfaces as described in the
  37.      Device Driver Programmer's Guide.
  38.  
  39. HHHHaaaarrrrddddwwwwaaaarrrreeee ggggrrrraaaapppphhhh ffffiiiilllleeeessssyyyysssstttteeeemmmm ((((hhhhwwwwggggffffssss))))
  40.      The internal hardware graph is exported to user-level through a pseudo-
  41.      file system (similar to /_p_r_o_c(4)).  The hwgfs file system represents the
  42.      collection of all interesting hardware and pseudo-devices as a file
  43.      system tree of special files and directories. It is mounted at ////hhhhwwww by the
  44.      kernel during system boot, and can be re-mounted using /_e_t_c/_m_n_t_h_w_g_f_s.  In
  45.      order to represent the directed _g_r_a_p_h as a Unix file system _t_r_e_e, hwgfs
  46.      imposes an artificial hierarchy on the hardware graph, and it uses hard
  47.      links and symlinks to represent graph edges that are outside that
  48.      hierarchy.  Note that it _i_s usually the case that the hwgfs file system
  49.      contains symlinks that point back "up" to higher-level directories. The
  50.      implication is that there will be some symlinks under ////hhhhwwww that form
  51.      _c_y_c_l_e_s which "ls -R" and other commands that recursively descend from a
  52.      directory have trouble dealing with.  Note, however, that the "find"
  53.      command handles symlinks very well and works as desired:
  54.  
  55.           find /hw -print | xargs ls -ld
  56.  
  57.      hwgfs does _n_o_t allow users to create or remove files or symlinks under
  58.      ////hhhhwwww.  Rather, this section of the file system hierarchy is controlled
  59.      exclusively by device drivers and other system software.  In other words,
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. hhhhwwwwggggrrrraaaapppphhhh((((4444))))                                                          hhhhwwwwggggrrrraaaapppphhhh((((4444))))
  71.  
  72.  
  73.  
  74.      ////hhhhwwww should be viewed purely as a _r_e_f_l_e_c_t_i_o_n of the contents of the
  75.      internal hardware graph. The contents of the graph and the links within
  76.      it may change across releases, and should not be depended upon.  They may
  77.      also change when new hardware releases.
  78.  
  79.      The internal hardware graph is updated dynamically when hardware is added
  80.      and removed, and the file system reflection of that graph is updated
  81.      accordingly.  For instance, when the _f_x(1m) utility is used to
  82.      repartition a disk drive, the special files used for the old partitioning
  83.      automatically disappear and new special files that represent the new
  84.      partitioning automatically appear.
  85.  
  86.      Since hwgfs is a pseudo-filesystem whose files don't actually use any
  87.      disk space, there is no persistent information associated with files
  88.      under ////hhhhwwww.  In particular, file attributes (mode, owner, group) are not
  89.      stored across reboots under hwgfs.  Rather, reasonable default are used
  90.      for all hwgfs special files.  These defaults can be changed in the normal
  91.      ways (i.e. with _c_h_m_o_d(1), _c_h_o_w_n(1), _c_h_g_r_p(1)), but the changes only last
  92.      until the next time the system is rebooted.  In order to supply the
  93.      appearance of special file attributes that are persistent across reboots,
  94.      hwgfs uses the _i_o_c_o_n_f_i_g(1m) utility, controlled by the contents of the
  95.      file /_e_t_c/_i_o_p_e_r_m_s.
  96.  
  97.      The ////ddddeeeevvvv directory is the root of the recommended path for all device
  98.      file usage, even though many of the files and directories under ////ddddeeeevvvv are
  99.      now symlinks into ////hhhhwwww.
  100.  
  101.      For example, device names under ////hhhhwwww should not be used when mounting
  102.      filesystems, or configuring the root filesystem for the kernel.  Only a
  103.      few administrative programs need to use the hardware graph pathnames
  104.      under ////hhhhwwww to obtain additional info directly from the hardware graph.
  105.  
  106.      System software (i.e. device drivers) may associate "labeled information"
  107.      with a hwgraph vertex.  In particular, _l_b_o_o_t(1m) provides the ability to
  108.      associate administrative information with an instance of a device using
  109.      DEVICE_ADMIN directives.  Such information is interpreted by the
  110.      appropriate device driver.  Additionally, system software (i.e. device
  111.      drivers) may choose to "export" such labeled information to user mode.
  112.      When this is done, the information is available as an extended user-level
  113.      attribute on the hwgfs file that represents that vertex; so it can be
  114.      obtained with an _a_t_t_r__g_e_t(2) call.
  115.  
  116. MMMMaaaajjjjoooorrrr////MMMMiiiinnnnoooorrrr NNNNuuuummmmbbbbeeeerrrrssss
  117.      As in earlier releases, the system uses a 32-bit identifier known as a
  118.      _d_e_v__t to identify a particular instance of a device (or special file).
  119.      In previous releases, a dev_t consisted of a "major number" -- which told
  120.      the system which driver to use -- and a "minor number" which was a magic
  121.      cookie interpreted by that driver.  Frequently a minor number was sliced
  122.      into various bit-fields, including a "unit number" which the device
  123.      driver used to index into an array of per-unit data structures.  For
  124.      backwards compatibility, the Irix kernel continues to support this model
  125.      for pseudo-drivers.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. hhhhwwwwggggrrrraaaapppphhhh((((4444))))                                                          hhhhwwwwggggrrrraaaapppphhhh((((4444))))
  137.  
  138.  
  139.  
  140.      For hwgraph-aware drivers, things are a bit different:  A 32-bit dev_t
  141.      still uniquely identifies a device; but the major number is always 0
  142.      (regardless of which driver owns the special file) and the minor number
  143.      is a system-wide unique "vertex handle".  From the vertex handle, system
  144.      software uses system-level hwgraph interfaces to determine exactly which
  145.      instance of a device is referenced.  The impact at user level is that
  146.      there is no way for user code to interpret minor numbers of a hwgraph-
  147.      aware device driver.  The driver writer may provide a library (DSO) with
  148.      appropriate formal interfaces for user-level operations, or the driver
  149.      writer can export useful information which the user can retrieve with
  150.      _a_t_t_r__g_e_t(2).
  151.  
  152.      Note that the dev_t (major/minor) for a particular device may change
  153.      across reboots.  In general, user code should not attempt to interpret
  154.      the bits in a _d_e_v__t, nor is there a valid reason to store a dev_t on
  155.      persistent storage for use across reboots.
  156.  
  157. IIIInnnntttteeeerrrrnnnnaaaallll hhhhwwwwggggrrrraaaapppphhhh IIIInnnntttteeeerrrrffffaaaacccceeeessss
  158.      There is an extensive set of interfaces that allow device drivers and
  159.      other system software to manipulate the hardware graph.
  160.  
  161.      Basic operations on vertices include:
  162.           create, destroy, clone, and get_next.
  163.  
  164.      Basic operations on edges include:
  165.           add, remove, and get_next.
  166.  
  167.      Basic operations on labeled vertex information include:
  168.           add, remove, replace, get, get_next, export, and unexport.
  169.  
  170.      There are many other operations, too.  These are all defined in the
  171.      Device Driver Programmer's Guide.
  172.  
  173. UUUUsssseeeerrrr----lllleeeevvvveeeellll IIIInnnntttteeeerrrrffffaaaacccceeeessss
  174.      At user-level, users continue to see special files which represent
  175.      hardware devices.  Users can create symlinks from normal file systems
  176.      that point into the hwgfs file system.
  177.  
  178.      The usual device driver operations (open, close, read, write, ioctl,
  179.      etc.) and the usual file operations (stat, attr_get, etc.) work as
  180.      expected.  As mentioned earlier, chmod, chown, and chgrp work, but only
  181.      until the next reboot.  For persistent changes to hwgfs special files,
  182.      the user must use _i_o_c_o_n_f_i_g(1m).  (This may change in a future release of
  183.      Irix.)
  184.  
  185.      The _l_s(1) command includes an 'S' option that can be used to display the
  186.      canonical device name for a specified hwgfs file or directory.  A
  187.      canonical device name is a path starting with ////hhhhwwww that unambiguously
  188.      identifies a device or collection of devices.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. hhhhwwwwggggrrrraaaapppphhhh((((4444))))                                                          hhhhwwwwggggrrrraaaapppphhhh((((4444))))
  203.  
  204.  
  205.  
  206. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  207.      aaaattttttttrrrr____ggggeeeetttt(2), ffffxxxx(1m), iiiiooooccccoooonnnnffffiiiigggg(1m), llllbbbbooooooootttt(1m), llllssss(1), MMMMAAAAKKKKEEEEDDDDEEEEVVVV(1m),
  208.      sssseeeettttddddeeeevvvvppppeeeerrrrmmmmssss(1m), lllliiiinnnnkkkkssssttttaaaatttt(1), nnnnssssttttaaaattttssss(1), ssssnnnn(1), xxxxbbbbssssttttaaaatttt(1m).
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.